Skip to content

feat: integrate KYC verification provider with identity provider abstraction#80

Open
Abdul-dev-creator wants to merge 2 commits into
Thalos-Infrastructure:mainfrom
Abdul-dev-creator:feat/kyc-integration
Open

feat: integrate KYC verification provider with identity provider abstraction#80
Abdul-dev-creator wants to merge 2 commits into
Thalos-Infrastructure:mainfrom
Abdul-dev-creator:feat/kyc-integration

Conversation

@Abdul-dev-creator

@Abdul-dev-creator Abdul-dev-creator commented Jul 18, 2026

Copy link
Copy Markdown

Overview

This PR integrates the first KYC (Know Your Customer) verification provider into the new Identity Provider abstraction. It introduces a provider-swappable IIdentityProvider interface with a mock provider implementation, enabling individual identity verification while exposing a standardized API to the rest of the platform.

Related Issue

Closes #72

Changes

⚙️ Identity Provider Abstraction

  • [ADD] src/kyc/interfaces/identity-provider.interface.ts

  • Added the IIdentityProvider interface defining createSession, getStatus, and processWebhook.

  • Supports provider-swappable architecture — replace the provider implementation without changing business logic.

  • [ADD] src/kyc/interfaces/kyc.types.ts

  • Defined the KycStatus enum: pending, in_review, �erified,
    ejected, �xpired.

  • Added shared interfaces for KYC sessions and database rows.

🤖 Mock KYC Provider

  • [ADD] src/kyc/providers/mock-kyc.provider.ts
  • Implemented the first KYC provider backed by an in-memory store.
  • Supports full state machine transitions via webhook events.
  • Handles verification failures and expiration.

🌐 KYC API Surface

  • [ADD] src/kyc/kyc.controller.ts

  • POST /kyc/session — Create a new KYC verification session (authenticated).

  • GET /kyc/status/:userId — Retrieve verification status for a user.

  • POST /kyc/webhook — Receive verification results from the provider.

  • [ADD] src/kyc/kyc.service.ts

  • Orchestrates provider calls and persists verification metadata to Supabase.

  • Syncs provider-side status with the local database on status checks.

🗄️ Database

  • [ADD] scripts/002_create_kyc_verifications.sql
  • Creates kyc_verifications table with columns: provider, provider_verification_id, status, metadata, verified_at.
  • Includes RLS policies and indexes.

🔧 Module Registration

  • [ADD] src/kyc/kyc.module.ts — NestJS module wired with Supabase and Auth dependencies.
  • [MOD] src/app.module.ts — Registered KycModule.
  • [MOD] .env.example — Added KYC_PROVIDER environment variable placeholder.

Verification

  • npm run lint ✅ (0 errors, pre-existing warnings only)
  • npm run build ✅ passed
  • npm test ✅ 48/48 tests passed

@Abdul-dev-creator
feat: integrate KYC verification provider with identity provider abst…
f45bc6e 
…raction

Adds the first KYC provider (mock-kyc) behind an IIdentityProvider
interface, enabling provider-swappable identity verification.

- IIdentityProvider abstraction (createSession, getStatus, processWebhook)
- MockKycProvider implementation with full state machine
- KycModule with POST /kyc/session, GET /kyc/status/:userId, POST /kyc/webhook
- kyc_verifications table migration (Supabase/PostgreSQL)
- Verification states: pending, in_review, verified, rejected, expired

Closes Thalos-Infrastructure#72
@vercel

vercel Bot commented Jul 18, 2026

Copy link
Copy Markdown

@Abdul-dev-creator is attempting to deploy a commit to the ManuelJG's projects Team on Vercel.

A member of the Team first needs to authorize it.

@Kalchaqui

Kalchaqui commented Jul 22, 2026

Copy link
Copy Markdown
Collaborator

Review — changes requested (do not merge yet)

Thanks @Abdul-dev-creator — the sketch (abstraction + Nest module + endpoints) is in the right direction for #72. Several blockers before this can land.

Blockers

  1. Migration numbering / collision with main

    • main already has scripts/002_create_kyb_verifications.sql (KYB).
    • This PR adds another 002_create_kyc_verifications.sql.
    • Rename to the next free number (e.g. 003_… / 005_… depending on what else lands — coordinate with Add TW retry queue and wire it into webhooks and escrows #103 retry-queue scripts).

  2. Confirm the user FK against the real Thalos schema

    • SQL uses REFERENCES auth.users(id) (same pattern as KYB’s migration).
    • Nest JWT subjects live in public.auth_users. Confirm those IDs actually exist in auth.users in your Supabase project — if not, inserts will fail at runtime. Prefer the FK that matches how identities are stored in staging.

  3. Security gaps on public routes

    • GET /kyc/status/:userId has no JWT → anyone can read any user’s KYC status (IDOR).
    • POST /kyc/webhook has no shared-secret / signature check → anyone can forge verified.
    • Gate status reads (caller must be the user or admin). Webhook must verify a provider secret (even for mock: e.g. KYC_WEBHOOK_SECRET header), same idea as Trustless Work webhooks.

  4. No tests

    • Add at least unit/integration coverage for: create session, status sync from provider, webhook success/failure, unauthorized status access.

Design / consistency with existing KYB

  1. main already has an Identity Provider abstraction under src/kyb/ (IdentityProvider + KYB_PROVIDER token + manual provider).

    • Don’t invent a second parallel IIdentityProvider without explaining how KYC and KYB share (or intentionally diverge). Prefer one shared contract or a clear KYC-specific interface that follows the same DI token pattern.

  2. Provider binding is hardcoded

    • KycService constructor always takes MockKycProvider. KYB uses a Symbol token so the provider is swappable via module binding — please match that so a real vendor (Persona/Sumsub/…) is a one-line DI change.

  3. sessionUrl incomplete

    • Service destructures sessionUrl from createSession, but MockKycProvider does not return it. Align the interface + mock (or stop advertising sessionUrl until a real provider exists).

What looks good

  • Status enum covers pending / in_review / verified / rejected / expired
  • Endpoints match the issue shape (POST /kyc/session, GET /kyc/status/:userId)
  • Persistence of provider + verification id + status + timestamps
  • Mock provider is fine as a first plug-in after the security/FK/DI fixes — call out clearly in the PR that it is not a production vendor

Happy to re-review after migration rename + FK fix + auth on status/webhook + tests.

This was referenced Jul 22, 2026
Merged
Open
josueazc added a commit to josueazc/ThalosBackend that referenced this pull request Jul 23, 2026
@josueazc
fix(verification): address review blockers (migration number, authz, …
3ddcfb3 
…SSoT docs)

- Rename migration 002_create_verifications.sql -> 004 to clear the number
  collision with kyb (002, main), kyc (Thalos-Infrastructure#80) and retry-queue (Thalos-Infrastructure#103) migrations.
- Tighten authorization on the compliance endpoints (IDOR fix): reads now
  require the caller to be the subject (users), an admin, or an internal
  service. Adds JwtOrInternalSecretGuard (JWT or x-thalos-internal-secret) and
  VerificationService.assertCanRead; unit tests cover self/admin/internal/denied.
- Document the single-source-of-truth model in the README: verifications is a
  read-only projection that KYC/KYB writers must upsert into, so Thalos-Infrastructure#71/Thalos-Infrastructure#72/Thalos-Infrastructure#75
  don't invent another status shape.
@ManuelJG1999

ManuelJG1999 commented Jul 25, 2026

Copy link
Copy Markdown
Collaborator

@Abdul-dev-creator could you please review the comments so we can move on?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Integrate KYC Verification Provider

3 participants

@Abdul-dev-creator @Kalchaqui @ManuelJG1999